package com.kexio.file.storage;

import java.io.InputStream;
import java.util.Map;

/**
 * 存储提供者接口
 * 
 * 定义文件存储的统一接口，支持多种存储后端：
 * - 本地文件系统
 * - MinIO/S3 兼容存储
 * - 阿里云 OSS
 * - 腾讯云 COS
 * - Azure Blob Storage
 * - Google Cloud Storage
 * 
 * @author Kexio Team
 * @since 1.0.0
 */
public interface StorageProvider {
    
    /**
     * 获取存储类型
     * 
     * @return 存储类型标识
     */
    String getStorageType();
    
    /**
     * 存储文件
     * 
     * @param bucketName 存储桶名称
     * @param objectKey 对象键/路径
     * @param inputStream 文件输入流
     * @param contentLength 内容长度
     * @param contentType 内容类型
     * @param metadata 元数据
     * @return 存储结果
     */
    StorageResult storeFile(String bucketName, String objectKey, InputStream inputStream, 
                           long contentLength, String contentType, Map<String, String> metadata);
    
    /**
     * 获取文件
     * 
     * @param bucketName 存储桶名称
     * @param objectKey 对象键/路径
     * @return 文件输入流
     */
    InputStream getFile(String bucketName, String objectKey);
    
    /**
     * 删除文件
     * 
     * @param bucketName 存储桶名称
     * @param objectKey 对象键/路径
     * @return 是否删除成功
     */
    boolean deleteFile(String bucketName, String objectKey);
    
    /**
     * 检查文件是否存在
     * 
     * @param bucketName 存储桶名称
     * @param objectKey 对象键/路径
     * @return 是否存在
     */
    boolean fileExists(String bucketName, String objectKey);
    
    /**
     * 获取文件信息
     * 
     * @param bucketName 存储桶名称
     * @param objectKey 对象键/路径
     * @return 文件信息
     */
    StorageFileInfo getFileInfo(String bucketName, String objectKey);
    
    /**
     * 生成预签名上传URL
     * 
     * @param bucketName 存储桶名称
     * @param objectKey 对象键/路径
     * @param expireMinutes 过期时间（分钟）
     * @param contentType 内容类型
     * @return 预签名URL
     */
    String generatePreSignedUploadUrl(String bucketName, String objectKey, 
                                     int expireMinutes, String contentType);
    
    /**
     * 生成预签名下载URL
     * 
     * @param bucketName 存储桶名称
     * @param objectKey 对象键/路径
     * @param expireMinutes 过期时间（分钟）
     * @return 预签名URL
     */
    String generatePreSignedDownloadUrl(String bucketName, String objectKey, int expireMinutes);
    
    /**
     * 复制文件
     * 
     * @param sourceBucket 源存储桶
     * @param sourceKey 源对象键
     * @param destBucket 目标存储桶
     * @param destKey 目标对象键
     * @return 是否复制成功
     */
    boolean copyFile(String sourceBucket, String sourceKey, String destBucket, String destKey);
    
    /**
     * 初始化存储桶
     * 
     * @param bucketName 存储桶名称
     * @return 是否创建成功
     */
    boolean createBucketIfNotExists(String bucketName);
    
    /**
     * 验证文件完整性
     * 
     * @param bucketName 存储桶名称
     * @param objectKey 对象键/路径
     * @param expectedHash 期望的哈希值
     * @return 验证结果
     */
    boolean verifyFileIntegrity(String bucketName, String objectKey, String expectedHash);
}
